home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / coll.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  22KB  |  515 lines
  1. /*
  2. *******************************************************************************
  3. *                                                                             *
  4. * COPYRIGHT:                                                                  *
  5. *   (C) Copyright Taligent, Inc.,  1996                                       *
  6. *   (C) Copyright International Business Machines Corporation,  1996-1999     *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.        *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure   *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                    *
  10. *                                                                             *
  11. *******************************************************************************
  12. */
  13. //=============================================================================
  14. //
  15. // File coll.h
  16. //
  17. // 
  18. //
  19. // Created by: Helena Shih
  20. //
  21. // Modification History:
  22. //
  23. //  Date        Name        Description
  24. // 02/5/97      aliu        Modified createDefault to load collation data from
  25. //                          binary files when possible.  Added related methods
  26. //                          createCollationFromFile, chopLocale, createPathName.
  27. // 02/11/97     aliu        Added members addToCache, findInCache, and fgCache.
  28. // 02/12/97     aliu        Modified to create objects from RuleBasedCollator cache.
  29. //                          Moved cache out of Collation class.
  30. // 02/13/97     aliu        Moved several methods out of this class and into
  31. //                          RuleBasedCollator, with modifications.  Modified
  32. //                          createDefault() to call new RuleBasedCollator(Locale&)
  33. //                          constructor.  General clean up and documentation.
  34. // 02/20/97     helena      Added clone, operator==, operator!=, operator=, copy
  35. //                          constructor and getDynamicClassID.
  36. // 03/25/97     helena      Updated with platform independent data types.
  37. // 05/06/97     helena      Added memory allocation error detection.
  38. //  6/20/97     helena      Java class name change.
  39. // 09/03/97     helena      Added createCollationKeyValues().
  40. // 02/10/98     damiba      Added compare() with length as parameter.
  41. // 04/23/99     stephen     Removed EDecompositionMode, merged with
  42. //                          Normalizer::EMode.
  43. //=============================================================================
  44.  
  45. #ifndef COLL_H
  46. #define COLL_H
  47.  
  48.  
  49. #include "locid.h"
  50. #include "utypes.h"
  51. #include "unistr.h"
  52. #include "normlzr.h"
  53.  
  54. class CollationKey;
  55.  
  56. /**
  57.  * The <code>Collator</code> class performs locale-sensitive
  58.  * <code>String</code> comparison. You use this class to build
  59.  * searching and sorting routines for natural language text.
  60.  *
  61.  * <p>
  62.  * <code>Collator</code> is an abstract base class. Subclasses
  63.  * implement specific collation strategies. One subclass,
  64.  * <code>RuleBasedCollator</code>, is currently provided
  65.  * and is applicable to a wide set of languages. Other
  66.  * subclasses may be created to handle more specialized needs.
  67.  *
  68.  * <p>
  69.  * Like other locale-sensitive classes, you can use the static
  70.  * factory method, <code>getInstance</code>, to obtain the appropriate
  71.  * <code>Collator</code> object for a given locale. You will only need
  72.  * to look at the subclasses of <code>Collator</code> if you need
  73.  * to understand the details of a particular collation strategy or
  74.  * if you need to modify that strategy.
  75.  *
  76.  * <p>
  77.  * The following example shows how to compare two strings using
  78.  * the <code>Collator</code> for the default locale.
  79.  * <blockquote>
  80.  * <pre>
  81.  * // Compare two strings in the default locale
  82.  * UErrorCode success = U_ZERO_ERROR;
  83.  * Collator* myCollator = Collator::createInstance(success);
  84.  * if( myCollator->compare("abc", "ABC") < 0 ) {
  85.  *     cout << "abc is less than ABC" << endl;
  86.  * }else{
  87.  *     cout << "abc is greater than or equal to ABC" << endl;
  88.  * }
  89.  * </pre>
  90.  * </blockquote>
  91.  *
  92.  * <p>
  93.  * You can set a <code>Collator</code>'s <em>strength</em> property
  94.  * to determine the level of difference considered significant in
  95.  * comparisons. Four strengths are provided: <code>PRIMARY</code>,
  96.  * <code>SECONDARY</code>, <code>TERTIARY</code>, and <code>IDENTICAL</code>.
  97.  * The exact assignment of strengths to language features is
  98.  * locale dependant.  For example, in Czech, "e" and "f" are considered
  99.  * primary differences, while "e" and "\u00EA" are secondary differences,
  100.  * "e" and "E" are tertiary differences and "e" and "e" are identical.
  101.  * The following shows how both case and accents could be ignored for
  102.  * US English.
  103.  * <blockquote>
  104.  * <pre>
  105.  * //Get the Collator for US English and set its strength to PRIMARY
  106.  * UErrorCode success = U_ZERO_ERROR;
  107.  * Collator* usCollator = Collator::createInstance(Locale::US, success);
  108.  * usCollator->setStrength(Collator::PRIMARY);
  109.  * if( usCollator->compare("abc", "ABC") == 0 ) {
  110.  *     cout << "'abc' and 'ABC' strings are equivalent with strength PRIMARY" << endl;
  111.  * }
  112.  * </pre>
  113.  * </blockquote>
  114.  * <p>
  115.  * For comparing <code>String</code>s exactly once, the <code>compare</code>
  116.  * method provides the best performance. When sorting a list of
  117.  * <code>String</code>s however, it is generally necessary to compare each
  118.  * <code>String</code> multiple times. In this case, <code>CollationKey</code>s
  119.  * provide better performance. The <code>CollationKey</code> class converts
  120.  * a <code>String</code> to a series of bits that can be compared bitwise
  121.  * against other <code>CollationKey</code>s. A <code>CollationKey</code> is
  122.  * created by a <code>Collator</code> object for a given <code>String</code>.
  123.  * <p>
  124.  * <strong>Note:</strong> <code>Collator</code>s with different Locale,
  125.  * CollationStrength and DecompositionMode settings will return different
  126.  * sort orders for the same set of strings. Locales have specific 
  127.  * collation rules, and the way in which secondary and tertiary differences 
  128.  * are taken into account, for example, will result in a different sorting order
  129.  * for same strings.
  130.  * <p>
  131.  * 
  132.  * @see         RuleBasedCollator
  133.  * @see         CollationKey
  134.  * @see         CollationElementIterator
  135.  * @see         Locale
  136.  * @see         Normalizer
  137.  * @version     1.7 1/14/97
  138.  * @author      Helena Shih
  139.  */
  140.  
  141. class U_I18N_API Collator 
  142. {
  143. public : 
  144.   
  145.   /**
  146.      * Base letter represents a primary difference.  Set comparison
  147.      * level to PRIMARY to ignore secondary and tertiary differences.
  148.      * Use this to set the strength of a Collator object.
  149.      * Example of primary difference, "abc" < "abd"
  150.      * 
  151.      * Diacritical differences on the same base letter represent a secondary
  152.      * difference.  Set comparison level to SECONDARY to ignore tertiary
  153.      * differences. Use this to set the strength of a Collator object.
  154.      * Example of secondary difference, "ä" >> "a".
  155.      *
  156.      * Uppercase and lowercase versions of the same character represents a
  157.      * tertiary difference.  Set comparison level to TERTIARY to include
  158.      * all comparison differences. Use this to set the strength of a Collator
  159.      * object.
  160.      * Example of tertiary difference, "abc" <<< "ABC".
  161.      *
  162.      * Two characters are considered "identical" when they have the same
  163.      * unicode spellings.
  164.      * For example, "ä" == "ä".
  165.      *
  166.      * ECollationStrength is also used to determine the strength of sort keys 
  167.      * generated from Collator objects.
  168.      */
  169.   enum ECollationStrength {
  170.     PRIMARY = 0,
  171.     SECONDARY = 1, 
  172.     TERTIARY = 2,
  173.     IDENTICAL = 3
  174.   };
  175.  
  176.   /**
  177.    * LESS is returned if source string is compared to be less than target
  178.    * string in the compare() method.
  179.    * EQUAL is returned if source string is compared to be equal to target
  180.    * string in the compare() method.
  181.    * GREATER is returned if source string is compared to be greater than
  182.    * target string in the compare() method.
  183.    * @see Collator#compare
  184.    */
  185.   enum EComparisonResult {
  186.     LESS = -1,
  187.     EQUAL = 0,
  188.     GREATER = 1
  189.   };
  190.   
  191.   /**
  192.    * Destructor
  193.    */
  194.   virtual                         ~Collator();
  195.  
  196.   /**
  197.    * Returns true if "other" is the same as "this"
  198.    */
  199.   virtual     bool_t              operator==(const Collator& other) const;
  200.  
  201.   /**
  202.    * Returns true if "other" is not the same as "this".
  203.    */
  204.   virtual     bool_t              operator!=(const Collator& other) const;
  205.  
  206.   /**
  207.    * Makes a shallow copy of the current object.
  208.    */
  209.   virtual     Collator*           clone(void) const = 0;
  210.   /**
  211.    * Creates the collator object for the current default locale.
  212.    * The default locale is determined by Locale::getDefault.
  213.    * @return the collation object of the default locale.(for example, en_US)
  214.    * @see Locale#getDefault
  215.    * The UErrorCode& err parameter is used to return status information to the user.
  216.    * To check whether the construction succeeded or not, you should check
  217.    * the value of U_SUCCESS(err).  If you wish more detailed information, you
  218.    * can check for informational error results which still indicate success.
  219.    * U_USING_FALLBACK_ERROR indicates that a fall back locale was used.  For
  220.    * example, 'de_CH' was requested, but nothing was found there, so 'de' was
  221.    * used.  U_USING_DEFAULT_ERROR indicates that the default locale data was
  222.    * used; neither the requested locale nor any of its fall back locales
  223.    * could be found.
  224.    * The caller owns the returned object and is responsible for deleting it.
  225.    */
  226.   static  Collator*           createInstance( UErrorCode&  err);
  227.  
  228.   /**
  229.    * Gets the table-based collation object for the desired locale.  The
  230.    * resource of the desired locale will be loaded by ResourceLoader. 
  231.    * Locale::ENGLISH is the base collation table and all other languages are 
  232.    * built on top of it with additional language-specific modifications.
  233.    * @param desiredLocale the desired locale to create the collation table
  234.    * with.
  235.    * @return the created table-based collation object based on the desired
  236.    * locale.
  237.    * @see Locale
  238.    * @see ResourceLoader
  239.    * The UErrorCode& err parameter is used to return status information to the user.
  240.    * To check whether the construction succeeded or not, you should check
  241.    * the value of U_SUCCESS(err).  If you wish more detailed information, you
  242.    * can check for informational error results which still indicate success.
  243.    * U_USING_FALLBACK_ERROR indicates that a fall back locale was used.  For
  244.    * example, 'de_CH' was requested, but nothing was found there, so 'de' was
  245.    * used.  U_USING_DEFAULT_ERROR indicates that the default locale data was
  246.    * used; neither the requested locale nor any of its fall back locales
  247.    * could be found.
  248.    * The caller owns the returned object and is responsible for deleting it.
  249.    */
  250.   static  Collator*           createInstance( const Locale&   loc,
  251.                           UErrorCode&      err);
  252.  
  253.   // comparison
  254.   /**
  255.    * The comparison function compares the character data stored in two
  256.    * different strings.  Returns information about whether a string
  257.    * is less than, greater than or equal to another string.
  258.    * <p>Example of use:
  259.    * <pre>
  260.    * .       UErrorCode status = U_ZERO_ERROR;
  261.    * .       Collator *myCollation = Collator::createInstance(Locale::US, status);
  262.    * .       if (U_FAILURE(status)) return;
  263.    * .       myCollation->setStrength(Collator::PRIMARY);
  264.    * .       // result would be Collator::EQUAL ("abc" == "ABC")
  265.    * .       // (no primary difference between "abc" and "ABC")
  266.    * .       Collator::EComparisonResult result = myCollation->compare("abc", "ABC");
  267.    * .       myCollation->setStrength(Collator::TERTIARY);
  268.    * .       // result would be Collator::LESS (abc" <<< "ABC")
  269.    * .       // (with tertiary difference between "abc" and "ABC")
  270.    * .       Collator::EComparisonResult result = myCollation->compare("abc", "ABC");
  271.    * </pre>
  272.    * @param source the source string to be compared with.
  273.    * @param target the string that is to be compared with the source string.
  274.    * @return Returns a byte value. GREATER if source is greater
  275.    * than target; EQUAL if source is equal to target; LESS if source is less
  276.    * than target
  277.    **/
  278.   virtual EComparisonResult   compare(    const   UnicodeString&  source, 
  279.                       const   UnicodeString&  target) const = 0;
  280.  
  281.   /**
  282.    * Does the same thing as compare but limits the comparison to a specified length
  283.    * <p>Example of use:
  284.    * <pre>
  285.    * .       UErrorCode status = U_ZERO_ERROR;
  286.    * .       Collator *myCollation = Collator::createInstance(Locale::US, status);
  287.    * .       if (U_FAILURE(status)) return;
  288.    * .       myCollation->setStrength(Collator::PRIMARY);
  289.    * .       // result would be Collator::EQUAL ("abc" == "ABC")
  290.    * .       // (no primary difference between "abc" and "ABC")
  291.    * .       Collator::EComparisonResult result = myCollation->compare("abc", "ABC",3);
  292.    * .       myCollation->setStrength(Collator::TERTIARY);
  293.    * .       // result would be Collator::LESS (abc" <<< "ABC")
  294.    * .       // (with tertiary difference between "abc" and "ABC")
  295.    * .       Collator::EComparisonResult result = myCollation->compare("abc", "ABC",3);
  296.    * </pre>
  297.    * @param source the source string to be compared with.
  298.    * @param target the string that is to be compared with the source string.
  299.    * @param length the length the comparison is limitted to
  300.    * @return Returns a byte value. GREATER if source (up to the specified length) is greater
  301.    * than target; EQUAL if source (up to specified length) is equal to target; LESS if source
  302.    * (up to the specified length) is less  than target.   
  303.    **/
  304.  
  305.   virtual EComparisonResult   compare(    const   UnicodeString&  source,
  306.                       const   UnicodeString&  target,
  307.                       int32_t length) const = 0;
  308.     
  309.     
  310.  
  311.   /** Transforms the string into a series of characters that can be compared
  312.    * with CollationKey::compareTo. It is not possible to restore the original
  313.    * string from the chars in the sort key.  The generated sort key handles 
  314.    * only a limited number of ignorable characters.
  315.    * <p>Use CollationKey::equals or CollationKey::compare to compare the
  316.    * generated sort keys.
  317.    * <p>Example of use:
  318.    * <pre>
  319.    * .       UErrorCode status = U_ZERO_ERROR;
  320.    * .       Collator *myCollation = Collator::createInstance(Locale::US, status);
  321.    * .       if (U_FAILURE(status)) return;
  322.    * .       myCollation->setStrength(Collator::PRIMARY);
  323.    * .       UErrorCode key1Status, key2Status;
  324.    * .       CollationKey CollationKey1
  325.    * .       CollationKey1 = myCollation->getCollationKey("abc", CollationKey1, key1Status);
  326.    * .       CollationKey CollationKey2
  327.    * .       CollationKey2 = myCollation->getCollationKey("ABC", CollationKey2, key2Status);
  328.    * .       if (U_FAILURE(key1Status) || U_FAILURE(key2Status)) { delete myCollation; return; }
  329.    * .       // Use CollationKey::compare() to compare the sort keys
  330.    * .       // result would be 0 (CollationKey1 == CollationKey2)
  331.    * .       int result = CollationKey1.compare(CollationKey2);
  332.    * .       myCollation->setStrength(Collator::TERTIARY);
  333.    * .       CollationKey1 = myCollation->getCollationKey("abc", CollationKey1, key1Status);
  334.    * .       CollationKey2 = myCollation->getCollationKey("ABC", CollationKey2, key2Status);
  335.    * .       if (U_FAILURE(key1Status) || U_FAILURE(key2Status)) { delete myCollation; return; }
  336.    * .       // Use CollationKey::compareTo to compare the collation keys
  337.    * .       // result would be -1 (CollationKey1 < CollationKey2)
  338.    * .       result = CollationKey1.compareTo(CollationKey2);
  339.    * .       delete myCollation;
  340.    * </pre>
  341.    * <p>If the source string is null, a null collation key will be returned.
  342.    * @param source the source string to be transformed into a sort key.
  343.    * @param key the collation key to be filled in
  344.    * @return the collation key of the string based on the collation rules.
  345.    * @see CollationKey#compare
  346.    */
  347.   virtual CollationKey&       getCollationKey(const   UnicodeString&  source,
  348.                           CollationKey&       key,
  349.                           UErrorCode&      status) const = 0;
  350.   /**
  351.    * Generates the hash code for the collation object
  352.    */
  353.   virtual int32_t             hashCode(void) const = 0;
  354.  
  355.   /**
  356.    * Convenience method for comparing two strings based on
  357.    * the collation rules.
  358.    * @param source the source string to be compared with.
  359.    * @param target the target string to be compared with.
  360.    * @return true if the first string is greater than the second one,
  361.    * according to the collation rules. false, otherwise.
  362.    * @see Collator#compare
  363.    */
  364.   bool_t              greater(    const   UnicodeString& source, 
  365.                   const   UnicodeString& target) const;
  366.   /**
  367.    * Convenience method for comparing two strings based on the collation
  368.    * rules.
  369.    * @param source the source string to be compared with.
  370.    * @param target the target string to be compared with.
  371.    * @return true if the first string is greater than or equal to the
  372.    * second one, according to the collation rules. false, otherwise.
  373.    * @see Collator#compare
  374.    */
  375.   bool_t              greaterOrEqual( const   UnicodeString& source, 
  376.                       const   UnicodeString& target) const;
  377.   /**
  378.    * Convenience method for comparing two strings based on the collation
  379.    * rules.
  380.    * @param source the source string to be compared with.
  381.    * @param target the target string to be compared with.
  382.    * @return true if the strings are equal according to the collation
  383.    * rules.  false, otherwise.
  384.    * @see Collator#compare
  385.    */
  386.   bool_t              equals( const   UnicodeString& source, 
  387.                   const   UnicodeString& target) const;
  388.         
  389.   // getter/setter
  390.   /**
  391.    * Get the decomposition mode of the collator object.
  392.    * @return the decomposition mode
  393.    * @see Collator#setDecomposition
  394.    */
  395.   Normalizer::EMode  getDecomposition(void) const;
  396.   /**
  397.    * Set the decomposition mode of the collator object. success is equal
  398.    * to U_ILLEGAL_ARGUMENT_ERROR if error occurs.
  399.    * @param the new decomposition mode
  400.    * @see Collator#getDecomposition
  401.    */
  402.   void                setDecomposition(Normalizer::EMode  mode);
  403.   /**
  404.    * Determines the minimum strength that will be use in comparison or
  405.    * transformation.
  406.    * <p>E.g. with strength == SECONDARY, the tertiary difference is ignored
  407.    * <p>E.g. with strength == PRIMARY, the secondary and tertiary difference
  408.    * are ignored.
  409.    * @return the current comparison level.
  410.    * @see Collator#setStrength
  411.    */
  412.   ECollationStrength  getStrength(void) const;
  413.   /**
  414.    * Sets the minimum strength to be used in comparison or transformation.
  415.    * <p>Example of use:
  416.    * <pre>
  417.    * .       UErrorCode status = U_ZERO_ERROR;
  418.    * .       Collator *myCollation = Collator::createInstance(Locale::US, status);
  419.    * .       if (U_FAILURE(status)) return;
  420.    * .       myCollation->setStrength(Collator::PRIMARY);
  421.    * .       // result will be "abc" == "ABC"
  422.    * .       // tertiary differences will be ignored
  423.    * .       Collator::ComparisonResult result = myCollation->compare("abc", "ABC");
  424.    * </pre>
  425.    * @see Collator#getStrength
  426.    * @param newStrength the new comparison level.
  427.    */
  428.   void                setStrength(    ECollationStrength  newStrength);
  429.   /**
  430.    * Get name of the object for the desired Locale, in the desired langauge
  431.    * @param objectLocale must be from getAvailableLocales
  432.    * @param displayLocale specifies the desired locale for output
  433.    * @param name the fill-in parameter of the return value
  434.    * @return display-able name of the object for the object locale in the
  435.    * desired language
  436.    */
  437.   static  UnicodeString&      getDisplayName( const   Locale&     objectLocale,
  438.                           const   Locale&     displayLocale,
  439.                           UnicodeString& name) ;
  440.   /**
  441.    * Get name of the object for the desired Locale, in the langauge of the
  442.    * default locale.
  443.    * @param objectLocale must be from getAvailableLocales
  444.    * @param name the fill-in parameter of the return value
  445.    * @return name of the object for the desired locale in the default
  446.    * language
  447.    */
  448.   static  UnicodeString&      getDisplayName( const   Locale&         objectLocale,
  449.                           UnicodeString&  name) ;
  450.  
  451.   /**
  452.    * Get the set of Locales for which Collations are installed
  453.    * @param count the output parameter of number of elements in the locale list
  454.    * @return the list of available locales which collations are installed
  455.    */
  456.   static  const   Locale*     getAvailableLocales(int32_t& count);
  457.  
  458.   /**
  459.    * Returns a unique class ID POLYMORPHICALLY.  Pure virtual method.
  460.    * This method is to implement a simple version of RTTI, since not all
  461.    * C++ compilers support genuine RTTI.  Polymorphic operator==() and
  462.    * clone() methods call this method.
  463.    *
  464.    * Concrete subclasses of Format must implement getDynamicClassID()
  465.    * and also a static method and data member:
  466.    *
  467.    *      static UClassID getStaticClassID() { return (UClassID)&fgClassID; }
  468.    *      static char fgClassID;
  469.    *
  470.    * @return          The class ID for this object. All objects of a
  471.    *                  given class have the same class ID.  Objects of
  472.    *                  other classes have different class IDs.
  473.    */
  474.   virtual UClassID getDynamicClassID(void) const = 0;
  475.  
  476. protected:
  477.   /**
  478.    * Constructors
  479.    */
  480.   Collator();
  481.   Collator(ECollationStrength collationStrength,
  482.        Normalizer::EMode decompositionMode);
  483.   Collator(const  Collator&   other);
  484.  
  485.   /**
  486.    * Assignment operator
  487.    */
  488.   const       Collator&       operator=(const Collator&   other);
  489.  
  490.   //--------------------------------------------------------------------------
  491. private:
  492.             
  493.   ECollationStrength  strength;
  494.   Normalizer::EMode  decmp;
  495. };
  496.  
  497. inline bool_t
  498. Collator::operator==(const Collator& other) const
  499. {
  500.   bool_t result;
  501.   if (this == &other) result = TRUE;
  502.   else result = ((strength == other.strength) && (decmp == other.decmp));
  503.   return result;
  504. }
  505.  
  506. inline bool_t
  507. Collator::operator!=(const Collator& other) const
  508. {
  509.   bool_t result;
  510.   result = !(*this == other);
  511.   return result;
  512. }
  513.  
  514. #endif
  515.